RuleManagerService - Installation & Configuration

COMPASS Version 6.2, 6.3, 6.4 © General Re Corporation 2021 - 2026. All Rights Reserved (created: 2026-06-16 generated: 2026-07-10)

Please note that this document is still under revision, so slight changes still might occur before the final version of this draft.

Version 6.2

Introduction

COMPASS 6.2 allows a client application to communicate with the COMPASS engine via REST Services. The COMPASS engine consists of the REST components CompassService and RuleManagerService.

From on COMPASS 6.2, the REST services have been split up into CompassService and RuleManagerService: CompassService is Compass' public API (described in detail here), RuleManagerService is the internal API used by RuleManagerApp and not meant for public usage.

Both CompassService and RuleManagerService are Web applications that need to be deployed in a Servlet Container or can run as a Spring Boot application. They work in a stateless manner, and as such it allows easy deployment and scalability including cloud architectures.

This document describes the installation and configuration of the RuleManagerService which is the backend for the RuleManagerApp and provides the necessary REST-services. Please note that this API should not be used by anyone but RuleManagerApp only. The publicly available REST methods provided by COMPASS are documented at REST-API

Prerequisites

RuleManagerService can be deployed in any Java servlet container that supports at least Servlet API 3.0. We recommend the lightweight Java web server Apache Tomcat.

From on version 6.2, RuleManagerService requires Java 11.

Functionality of the RuleManager Service

REST-Services provided by RuleManagerService and used by RuleManagerApp are for internal use only and therefore are not described here.

Installation

The RuleManagerService distribution consists of the archive RuleManagerService.war. It can be deployed in a Servlet Container (see Deployment in a Servlet Container) or as a standalone application using Spring Boot (see Standalone Server (Spring Boot)).

Deployment in a Servlet Container

RuleManagerService.war containing the RuleManagerService should be deployed in your Servlet Container (i.e. Tomcat: webapps directory, OpenLiberty: dropins directory). If required, restart the container.

Standalone Server (Spring Boot)

The RuleManagerService.war contains a runnable environment that can be started with the spring WarLauncher. For quick testing, it is possible to start the WebApp without a third-party Servlet Container:

Copy RuleManagerService.war file to your Compass lib directory.

Make sure Java 11 is installed, and run the following command using Java 11:

java -cp lib\RuleManagerService.war;databaseDriver org.springframework.boot.loader.WarLauncher  --spring.configname=RuleManagerService

The delivery includes a batch file bin\startRuleManagerService.bat that starts RuleManagerService as a Spring Boot application.

Configuration

RuleManagerService needs configuration files which define the environment and the data to work with. This configuration-file may use one of the following formats:

Format File-Name

Properties

RuleManagerService.properties

YAML

RuleManagerService.yml

JSON

RuleManagerService.json

Following, we will explain the configuration as properties. The difference between the formats mentioned above are explained in RuleManagerService.properties - application.properties

The main property file is called either RuleManagerService.properties (default file name) or RuleManagerService.yml; in Open Liberty, the file needs to be named application.properties. The contents of the files are described in detail in RuleManagerService.properties - application.properties. We strongly recommend using COMPASS’ ability to use DataSources instead of pure JDBC calls. Therefore, please create the appropriate DataSources (see Data Source properties).

Spring Boot

When the RuleManagerService is started as a Spring Boot application with the batch file bin\startRuleManagerService.bat, the path to the configuration-file is:

config\RuleManagerService.properties

The file name is defined by the --spring.config.name parameter in said file (see Standalone Server (Spring Boot)) and should be located in the [COMPASS-installation]/Config directory.

Apache Tomcat / Standard Servlet Container

The following instructions describe the standard procedure of a deployment within a Standard Servlet Container. As an example, deployment within Apache Tomcat is explained:

When the RuleManagerService is being deployed within a Standard Servlet Container, it is up to the administrator to place to file RuleManagerService.properties to any location and adapt the environment-entry in RuleManagerService/META-INF/context.xml accordingly, i.e.

$CATALINA_HOME/COMPASSConfig/RuleManagerService.properties

The location of the above mentioned file is defined in RuleManagerService/META-INF/context.xml, and can be adapted:

<?xml version="1.0" encoding="UTF-8"?>
    <Context path="/">
        <Environment    name="spring.config.location"
                        value="file:../COMPASSConfig/RuleManagerService.properties"
                        type="java.lang.String"/>

The file RuleManagerervice.properties is part of the installation package and will be delivered outside the WAR archive.

Open Liberty / WebSphere

The following instructions describe the procedure of a deployment within an IBM’s Open Liberty. It is also a template for deployment within IBM’s WebSphere. As an example, deployment within Open Liberty is explained:

When RuleManagerService is being deployed in Open Liberty, the file application.properties needs to be placed in $/{server.config.dir} i.e. /opt/wlp/usr/servers/defaultServer.

The default context name of RuleManagerService is "RuleManagerService". If this needs to be changed, the WAR archive of RuleManagerService needs to be unpacked and the file WEB-INF/classes/ibm-web-ext.xml needs to be adapted. The context name can be changed by editing the entry context-root:

 <web-ext xmlns="http://websphere.ibm.com/xml/ns/javaee"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://websphere.ibm.com/xml/ns/javaee
   http://websphere.ibm.com/xml/ns/javaee/ibm-web-ext_1_0.xsd"
   version="1.0">

   <reload-interval value="0"/>
   <context-root uri="/RuleManagerService"/>
   <enable-file-serving value="true"/>
   <enable-reloading value="true"/>
</web-ext>

After editing, the WAR archive needs to be re-packed and can be deployed.

Wildfly / JBoss

If you haven’t done so, deploy your database driver to JBoss / Wildfly and create the DataSources needed for COMPASS (see example below). You can also configure RuleManagerService in such a way that it uses pure JDBC connections (see Installation: Database), however, we strongly recommend to use DataSources when deploying RuleManagerService on JBoss / WildFly.

Since there are multiple options specifying DataSources in JBoss / WildFly, our example below shows one possible way to define the DataSources. We therefore adapt %JBOSS_HOME%/standalone/configuration/standalone.xml. If you want to configure the DataSources in a different way, please consult the documentation of your application server or talk to your database administrator.

        <subsystem xmlns="urn:jboss:domain:datasources:6.0">
            <datasources>
                <datasource jndi-name="java:jboss/COMPASSKnowledge" pool-name="COMPASSKnowledge">
                    <connection-url>jdbc:mariadb://localhost:3306/dbname</connection-url>
                    <driver-class>org.mariadb.jdbc.Driver</driver-class>
                    <driver>mariadb-java-client-2.7.1.jar</driver>
                    <security>
                        <user-name>user</user-name>
                        <password>password</password>
                    </security>
                    <validation>
                        <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker"/>
                        <validate-on-match>true</validate-on-match>
                        <background-validation>false</background-validation>
                        <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter"/>
                    </validation>
                </datasource>
                <datasource jndi-name="java:jboss/COMPASSCache" pool-name="COMPASSCache">
                    <connection-url>jdbc:mariadb://localhost:3306/dbname</connection-url>
                    <driver-class>org.mariadb.jdbc.Driver</driver-class>
                    <driver>mariadb-java-client-2.7.1.jar</driver>
                    <security>
                        <user-name>user</user-name>
                        <password>password</password>
                    </security>
                </datasource>
                <datasource jndi-name="java:jboss/COMPASSCase" pool-name="COMPASSCase">
                    <connection-url>jdbc:mariadb://localhost:3306/dbname</connection-url>
                    <driver-class>org.mariadb.jdbc.Driver</driver-class>
                    <driver>mariadb-java-client-2.7.1.jar</driver>
                    <security>
                        <user-name>user</user-name>
                        <password>password</password>
                    </security>
                </datasource>
            </datasources>
        </subsystem>

When RuleManagerService is being deployed within a Standard Servlet Container, it is up to the administrator to place to file RuleManagerService.properties to any location and adapt the environment-entry in the deployment descriptor WEB-INF/web.xml accordingly (reminder: you’ll have to re-package the war archive and re-deploy).

Let’s say the configuration file is in $JBOSS_HOME, the entry would look like

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
		  http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
         version="3.0">
    <env-entry>
        <env-entry-name>spring.config.location</env-entry-name>
        <env-entry-type>java.lang.String</env-entry-type>
        <env-entry-value>file:../COMPASSConfig/RuleManagerService.properties</env-entry-value>
    </env-entry>
</web-app>

In JBoss / WildFly, if running them with default logging configuration, the archive SL4J needs to be excluded from COMPASS' classpath. This has already been configured inside the web app at META-INF/jboss-deployment-structure.xml - so if this needs to be changed again, please adapt said file and re-package the war archive.

<jboss-deployment-structure>
    <deployment>
    <!-- Exclusions allow you to prevent the server from automatically adding some dependencies     -->
        <exclusions>
            <module name="org.slf4j" />
            <module name="org.slf4j.impl" />
        </exclusions>
    </deployment>
</jboss-deployment-structure>

Profiles

RuleManagerService works with profiles regarding Authorization / Authentication. Depending on the chosen profile, RuleManagerService will either use Spring Authorization (OAuth2) or Keycloak. It is also possible to run RuleManagerService without any Authorization / Authentication.

The desired Authorization / Authentication option is to specified in the property spring.profiles.active in the file RuleManagerService.properties or RuleManagerService.yml (see Configuration).

There are 5 profiles available to customize the type of Authorization / Authentication:

Table 1. Authorization Profiles
Profile Explanation

default

Mandatory

keycloakAuthorization

Activate the Keycloak Authorization Configuration

springAuthorization

Activate Spring Authorization Configuration

noAuthorization

Service Endpoints are not secured. RuleManagerApp does not ask for a user/password

dbAuthorization

Service Endpoints are not secured. RuleManagerApp will ask for user/password, which will be confirmed by RuleManagerService

2 profiles need to be specified - default plus the corresponding Authorization profile. The profile default always needs to be specified plus either one of the profiles keycloakAuthorization, springAuthorization or noAuthorization .

If not exactly 2 profiles are specified or if the profile default is missing, the application will not start.
Table 2. Valid Authorization Profiles
Profiles Explanation

spring.profiles.active=default,springAuthorization

RuleManagerService secured by Spring Authorization

spring.profiles.active=default,keycloakAuthorization

RuleManagerService secured by Keycloak Authorization

spring.profiles.active=default,noAuthorization

Endpoints are not secured

spring.profiles.active=default,dbAuthorization

Endpoints are not secured

RuleManagerService.properties - application.properties

Usually, configuration properties are specified in the file RuleManagerService.properties. In Open Liberty (WebSphere), the file application.properties is used instead.

The content of both these files is identical and can be grouped into 4 sections: System properties, Spring Boot related properties, authorization properties and logging properties.

It is also possible to pass the configuration-properties as command-line-parameters to RuleManagerService.

System properties

RuleManagerService stores some information in the property-files mentioned below. Those properties are defined in the file [compass.server.home]/config/server/compass.properties.

In addition, RuleManagerService needs to know the system-name to work with and additional properties when being started.

After modification of any of above-mentioned parameters, the web server should be restarted for the changes to take effect.

The following 3 properties are used to configure these:

Property Name Description

rulemanager.server.home

Location where the 3 above mentioned files/directory are located.
For Spring Boot, start with the default batch file set to rulemanager.server.home=. It is also possible to define an absolute path.

Example for Apache Tomcat:
rulemanager.server.home=${CATALINA_HOME}/COMPASSConfig

Example for Open Liberty / WebSphere:
rulemanager.server.home=${server.config.dir}/COMPASSConfig_

rulemanager.systemname

Name of the system to be used, and which is defined in compass.properties

rulemanager.fullloadsystem

true or false:
A simple preload is always done at start-up. Should this property be set to true, the whole Knowledge Data gets loaded into memory at application start-up, which results in a longer start-up time.

Spring Boot properties

The following properties are used to configure RuleManagerService when started outside a Servlet Container but being run as a Spring Boot application.

When running in a Servlet Container, these values are typically defined within the Servlet Container and can be omitted (commented out).

Property Name Description

server.port

REST service is listening on this port, only relevant if the service is running stand-alone

server.servlet.contextPath

REST API prefix, only relevant if service is running stand-alone

server.sessionTimeout

timeout, only relevant if the service is running stand-alone

spring.jmx.enabled

Don’t expose management beans to the JMX domain

Data Source properties

The next property allows the definition of a Java Datasource for the database connection to access the: Knowledge Ddta. Set value to "none", if you don’t want to use a DataSource but want to use the database configuration in ${compass.server.home}/config/server/compass.properties Set values to a JNDI Value, if you want to use Datasource of the servlet container. For Apache Tomcat, define <ResourceLink> in context.xml and <Resource> in server.xml needs to be defined..

Property Name Description

knowledge.datasource.jndi

Datasource for knowledge data

Should the entry xxxxxx.datasource.jndi be set to none or to a value that has not really been defined in the servlet container, a JDBC database connection will be created using the system-properties from the file $\{compass.server.home}/config/server/compass.properties.

When defining the Datasource for the Knowledge Data, the corresponding connection-properties in the compass.properties-file can be omitted:

Knowledge Data:

[System-name].database.url
[System-name].database.driver
[System-name].database.user
[System-name].database.password

Authorization properties

This part is only required when the RuleManagerService is used together with the COMPASS Authorization Server (OAuth2), meaning the profiles default and `springAuthorization`are activated (see Profiles). The installation of COMPASS Authorization Server providing OAuth2-authorization is described in the document Authorization Server. The corresponding properties are described in the document REST-API-Security

Property Name Description

compass.security.enabled

define if security is enabled

compass.security.cors,enabled

define if CORS is enabled

compass.security.cors.crossOrigin.urls

specify URLs for which CORS is allowed. URLs have to be entered incl. protocol (i.e. http / https) and port. Multiple URLs cam be entered as a list separated by comma

compass.security.resource_id

define the security resource id

compass.security.oauthServerUrl

define the OAuth server URL for the check_token method

compass.security.clientId

define the client id for the oauth server

compass.security.clientSecret

define the client password for the oauth server

compass.security.tokenValidationTimeout

define the timeout for the validation token (0 = no timout)

spring.security.oauth2.resourceserver.jwt.issuer-uri

In case you want to integrate with Keycloak, specify the URL for the specific Keycloak-realm

RuleManagerService - configuration examples

Example configuration via property-file

Details
# COMPASS 6.2 RuleManagerService Properties
#
# this block is only relevant if the service is running stand-alone
# RuleManager service is listening on this port
server.port=8086
# REST API prefix
server.servlet.contextPath=/RuleManagerService
# timeout, in seconds
server.sessionTimeout=60
#
# REST api Version
rulemanager.parameter.apiVersion=1.0
#
# Don't expose management beans to the JMX domain.
spring.jmx.enabled=false
# Logging
# log levels
logging.level.root=INFO
logging.level.org.springframework.web=INFO
# set COMPASS REST logging to debug
logging.level.com.cr.compass.rest=DEBUG
logging.level.com.cr.compass.rest.term=INFO
# set the FOP engine outputs only to error
logging.level.org.apache.fop=ERROR
#
# logging of Requests
logging.level.org.springframework.web.filter.CommonsRequestLoggingFilter=INFO
#
# logging file  - comment out the relevant
# for running stand-alone or for running in tomcat
logging.file.name=./log/RuleManagerService.log

# Logging pattern for the logging file and console
logging.pattern.file=%d{ISO8601} [%-5level] %logger{15}:%L - %msg%n
logging.pattern.console=%d{ISO8601} [%highlight(%-5level)] %cyan(%logger{15}:%L) - %msg%n
#
# Logging-Area of the COMPASS kernel
rulemanager.loggingarea=0
#
# COMPASS properties files location - comment out the relevant
# COMPASS properties files are in an absolute path or relative path (starting with . )
rulemanager.server.home=./configSamples
# COMPASS properties files are under user.home to catalina home
#rulemanager.server.home=${CATALINA_HOME}/COMPASSConfig
# you need these files and directories for a service installation
# ${rulemanager.server.home}/config/server/compass.properties
# ${rulemanager.server.home}/config/server/EMConversion.properties
# ${rulemanager.server.home}/config/script/*.*
#
# System to use, must be declared in ${rulemanager.server.home}/config/server/compass.properties
rulemanager.systemname=aSystem
# the COMPASS system is being preloaded in all cases. The next property describes if the preload includes the whole (full) database
rulemanager.fullloadsystem=false

# DataSources Configuration
# set value to "none", if you don't want to use DataSources
# and you want to use the database configuration in ${rulemanager.server.home}/config/server/compass.properties
knowledge.datasource.jndi=none

# set values to a JNDI Value, if you want to use DataSources of the servlet container
# for tomcat define <ResourceLink> in context.xml and <Resource> in server.xml for knowledge DataSources
#knowledge.datasource.jndi=java:/comp/env/jdbc/COMPASSKnowledge

# login check should be enabled only for RuleManagerService
compass.login.check.enabled=true

# COMPASS PROFILE. Check Readme file for more details on profile #
spring.profiles.active=default,noAuthorization

# authentication and authorization
# CORS POLICY
compass.security.cors.enabled=true
compass.security.cors.crossOrigin.urls=http://aHost:8085,http://anotherHost:4200
# SPRING AUTHORIZATION #
# define the oauth server url for the check_token method
compass.security.oauthServerUrl=http://aHost:8080/CompassAuthorization/oauth/check_token
# define the security resource id
compass.security.resource_id=compass-service
# define the client id for the oauth server
compass.security.clientId=rm-client
# define the client pwd for the oauth server
compass.security.clientSecret=rm-client-secret
# define the token validation timeout in minutes if security is enabled.
# Authorization Token will be validated only after the specified timeout in minutes
compass.security.tokenValidationTimeout=0
# SPRING AUTHORIZATION END #

# KEYCLOAK AUTHORIZATION #
spring.security.oauth2.resourceserver.jwt.issuer-uri=http://aHost:8085/realms/RuleManager
# KEYCLOAK AUTHORIZATION END #----

Example configuration via YAML-file

Details
# config RuleManagerService for 6.2
server:
  port: '8086'
  servlet:
    contextPath: "/RuleManagerService"
rulemanager:
  systemname: aSystem
  parameter:
    fullloadsystem: false
    loggingarea: 0
compass:
  language: en
  login:
    check:
      enabled: true
  database:
    global:
      url: jdbc:mariadb://aHost:3306/aDatabase
      driver: org.mariadb.jdbc.Driver
      user: aUser
      password: aPassword
  security:
    cors:
      enabled: true
      crossOrigin:
        urls: http://aHost:8085,http://anotherHost:4200
    clientId: rm-client
    clientSecret: rm-client-secret
    oauthServerUrl: http://aHost:8080/CompassAuthorization/oauth/check_token
    resource_id: compass-service
    tokenValidationTimeout: 0
logging:
  file:
    name: ./log/RuleManagerService.log
  level:
    root: INFO
    com:
      cr:
        compass:
          rest: DEBUG
  pattern:
    file: "%d{ISO8601} [%-5level] %logger{15}:%L - %msg%n"
    console: "%d{ISO8601} [%highlight(%-5level)] %cyan(%logger{15}:%L) - %msg%n"
spring:
  profiles:
    active: default,noAuthorization
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: http://10.130.130.115:8085/realms/RuleManager----

Example configuration via JSON-file / JSON parameter

Details
{
  "server": {
	"port": "8086",
	"servlet": {
	  "contextPath": "/RuleManagerService"
	}
  },
  "rulemanager": {
	"systemname": "aSystem",
	"parameter": {
	  "fullloadsystem": false,
	  "loggingarea": 0
	}
  },
  "compass": {
	"language": "en",
	"login":{
	  "check": {
		"enabled": true
	  }
	},
	"database": {
	  "global": {
		"url": "jdbc:mariadb://aHost:3306/aDatabase",
		"driver": "org.mariadb.jdbc.Driver",
		"user": "aUser",
		"password": "aPassword"
	  }
	},
	"security": {
	  "cors": {
		"enabled": true,
		"crossOrigin": {
		  "urls": "http://aHost:8085,http://anotherHost:4200"
		}
	  },
	  "clientId": "rm-client",
	  "clientSecret": "rm-client-secret",
	  "oauthServerUrl": "http://aHost:8080/CompassAuthorization/oauth/check_token",
	  "resource_id": "compass-service",
	  "tokenValidationTimeout": 0
	}
  },
  "logging": {
	"file": {
	  "name": "./log/RuleManagerService.log"
	},
	"level": {
	  "root": "INFO",
	  "com": {
		"cr": {
		  "compass": {
			"rest": "DEBUG"
		  }
		}
	  }
	},
	"pattern": {
	  "file": "%d{ISO8601} [%-5level] %logger{15}:%L - %msg%n",
	  "console": "%d{ISO8601} [%highlight(%-5level)] %cyan(%logger{15}:%L) - %msg%n"
	}
  },
  "spring": {
	"profiles": {
	  "active": "default,noAuthorization"
	},
	"security": {
	  "oauth2": {
		"resourceserver": {
		  "jwt": {
			"issuer-uri": "http://10.130.130.115:8085/realms/RuleManager"
		  }
		}
	  }
	}
  }
}

Integration with Keycloak

In order to run RuleManagerService, the following profiles have to be activated in the file RuleManagerService.properties or RuleManagerService.yaml (see RuleManagerService.poperties / application.properties. A Customer Keycloak Realm Issuer URL needs to be configured.

The Issuer Url can be found if you open Keycloak Admin Console, select the corresponding Realm and click Realm Settings. On the right side, you will find the OpenID Endpoint Configuration link. Click the link, it will open a new tab and on the beginning, you will find the Issuer Url.
Example 1. Example from Keycloak

"issuer":"http://localhost:8080/realms/RuleManagerApp"

Example 2. Example configuration in RuleManagerService
spring.profiles.active=default,keycloakAuthorization
spring.security.oauth2.resourceserver.jwt.issuer-uri=http://localhost:8080/realms/RuleManagerApp

Logging

RuleManager Service

In RuleManagerService logging can be configured as properties in the file RuleManagerService.[properties | yaml | json]. For a full overview about properties and logging features in RuleManagerService, see Properties Overview of RuleManagerService.
For real-world examples of how to configure RuleManagerService, see How to pass properties.

Verifying the installation

After updating the configuration-file, the installation needs to be verified.

For both installation types (Spring Boot app - standalone - or deployment in a Servlet Container, please perform the following steps:

Deployment as Spring Boot app (stand-alone)

  • Start RuleManagerService as Spring Boot app (stand-alone):

[COMPASS-installation-directory]/bin/startRESTService.bat
  • Verify in your console, that RuleManagerService started:

In the CMD-window or the log-file specified, you should see a message like

2023-03-14 13:05:47,299 [INFO ] c.c.c.r.RuleManagerServiceApp:61 - Started RuleManagerServiceApp in 65.43 seconds (JVM running for 308.249)

Deployment in Servlet Container

Perform the following steps:

  • Start the Servlet Container if not already started and deploy the application

  • Check that the RuleManagerService was deployed correctly (using administration tools of your Web Server).

  • Alternatively, you can check the logfile you’ve specified: It should contain an entry like

2023-03-14 13:05:47,299 [INFO ] c.c.c.r.RuleManagerServiceApp:61 - Started RuleManagerServiceApp in 65.43 seconds (JVM running for 308.249)